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Abstract 

The  OFFSRF  format  defines  a  record  structure  for  files  to  be  used  as  input  to  computer  pro¬ 
grams.  The  original  application  was  offset  data  for  ship  hulls,  but  the  format  itself  is  very 
general.  It  is  most  suitable  for  comparatively  small  sets  of  data  which  are  often  modified  using 
ordinary  text  editors. 

When  OFFSRF  was  originally  designed,  several  Fortran  subroutines  were  provided  to  ease 
the  use  of  the  format  for  programmers.  In  this  document  the  programmer  support  is  extended 
to  the  language  C-l— 1-.  C-H-  classes  are  described  which  can  be  used  to  read  and  write  files  in 
OFFSRF  format. 


Resume 

Le  format  OFFSRF  definit  une  structure  d’enregistrement  pour  les  fichiers  qui  doivent  servir  aux 
entries  dans  des  logiciels.  L’application  initiale  etait  celle  des  donnees  de  decalage  pour  les  co- 
ques  de  navire,  mais  le  format  comme  tel  est  tres  general.  II  convient  specialement  aux  ensembles 
de  donnees  relativement  petits  et  souvent  modifies  a  I’aide  d’editeurs  de  texte  ordinaires. 

Au  moment  de  la  conception  d’OFFSRF,  plusieurs  sous-programmes  en  FORTRAN  ont 
4te  fournis  afin  que  les  programmeurs  puissent  utiliser  le  format  plus  facilement.  Ce  document 
etend  le  soutient  offert  en  englobant  le  langange  C-|-t-,  et  il  decrit  des  classes  qui  peuvent 
s’utiliser  pour  la  lecture  et  I’ecriture  avec  des  fichiers  en  format  OFFSRF. 
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1  Introduction 


The  OFFSRF  format  for  computer  data  files[l]  was  designed  to  provide  a  well-structured 
format  for  comparatively  small  files  which  are  often  modified  using  ordinary  text  editors.  The 
original  application  was  offset  data  for  ship  hulls,  but  the  format  itself  is  very  general. 

When  OFFSRF  was  first  proposed,  several  Fortran  subroutines  were  provided  to  ease  the 
use  of  the  format  for  programmers.  In  this  document  the  programmer  support  is  extended  to 
the  language  C-f-t-.  classes  are  described  which  can  be  used  for  reading  and  writing  files 

in  OFFSRF  format. 

To  use  the  classes  described  here,  you  must  include  the  header  file  OFFSRF. h  in  your  appli¬ 
cation.  Check  with  your  system  manager  to  see  whether  this  file  is  installed  on  your  system. 

The  OFFSRF  classes  make  use  of  a  representation  of  character  strings  defined  by  the  str 
class.  Its  definition  may  be  found  in  the  file  str.h.  The  member  functions  of  the  str  class  are 
described  in  Appendix  A. 


2  OFFSRF  Input  and  Output  Streams 

OFFSRF. h  defines  two  new  I/O  streams:  one  for  input  from  an  OFFSRF  file,  and  one  for 
output  to  an  OFFSRF  file.  They  are  called  0FFSRF_if  stream  and  OFFSRF _of  stream  respectively 
and  are  specializations  of  the  standard  C+-I-  I/O  classes  ifstream  and  ofstream  normally 
defined  in  f stream. h. 

2.1  Constructors 

The  constructors  for  the  0FFSRF_if  stream  and  OFFSRF  .ofstream  classes  both  require  a 
char*  argument  which  is  interpreted  as  the  name  of  the  file  to  be  connected  to  the  stream. 
There  is  a  second,  optional  int  argument  which  controls  the  stream’s  behaviour  if  it  is  unable 
to  open  the  file:  if  the  argument  is  one,  an  error  message  is  written  to  cout  and  program 
execution  is  aborted;  if  it  is  zero,  the  execution  continues  but  the  value  of  the  stream  when 
interpreted  as  an  int  is  zero.  If  the  second  argument  is  not  given,  its  value  defaults  to  one:  i.e. 
a  fatal  error  message  is  written.  The  declarations 

OFFSRF J.f stream  inC'test .  in") ; 

OFFSRF stream  inC'test .  in" ,  1)  ; 

and 

OFFSRF J.f  stream  inC'test .  in"  ,0) ; 
if  (Istream)  open.J'ile.errC'test.in") ; 

are  all  equivalent.  The  function  openJile.errO  writes  the  fatal  error  message. 


2.2  File  Paths 


The  HLLFLO  programs[2],  for  which  the  OFFSRF  format  was  originally  developed,  allow 
users  to  indicate  a  set  of  directories  in  which  the  HLLFLO  programs  should  look  for  files.  This  is 
done  by  creating  a  file  called  .f  ilsub  in  the  user’s  home  directory.  Each  line  of  this  file  contains 
a  directory  name.  Whenever  a  HLLFLO  program  opens  an  existing  file,  it  first  looks  for  the  file 
on  the  connected  directory,  then  in  each  of  the  directories  in  .f  ilsub  until  the  file  is  found. 

This  file  path  mechanism  is  also  implemented  for  the  OFFSRF-if  stream  class.  When  the 
stream  is  connected  to  a  file,  the  directories  in  $H0ME/.f ilsub  will  be  searched  until  a  file  of 
the  correct  name  is  found. 

2.3  Skipping  of  comments  by  OFFSRPJfBtieazn 

An  0FFSRF_if  stream  overloads  the  ws  manipulator  so  that  OFFSRF  comments  are  skipped 
as  well  as  whitespace:  i.e.  any  characters  between  an  exclamation  point  and  the  end  of  line  will 
be  ignored.  Moreover,  the  extractor  >>  is  overloaded  so  that  when  variables  of  types  short, 
int,  long,  unsigned  short,  imsigned  int,  unsigned  long,  float,  or  double  are  read,  the 
whitespace  and  comments  preceding  them  are  always  skipped.  This  is  in  conformance  with  the 
OFFSRF  paradigm  that  the  exact  position  of  a  number  on  a  line  should  not  be  important.  This 
is  not  true  for  char  data  for  which  whitespace  may  be  significant. 

For  example,  suppose  that  the  file  test .  in  contains  the  following  data. 

!This  is  a  comment  followed  by  a  blank  line 

123 

Then  the  program 

•include  " OFFSRF. h" 
mainO 
{ 

OFFSRF-ifstream  streamC'test  .in") ; 
int  i; 

stream  »  i; 

cout  «  "i  =  "  <<  i  <<  endl; 

} 

will  correctly  output 
i  *  123 

The  OFFSRF  comment  line,  the  blank  line,  and  the  spaces  before  the  number  123  are  skipped. 

When  a  string  (either  a  variable  of  class  str  or  a  chaur*)  is  read  by  the  inserter  for  an 
ifstream,  the  string  is  delimited  by  whitespace  characters.  An  OFFSRF _if  stream  allows  the 
inclusion  of  non-end-of-line  whitespace  in  the  string.  Use  the  manipulator  str.ws  to  allow 
whitespace  in  the  strings.  Use  the  manipulator  no_str_ws  to  forbid  it.  By  default,  whitespace 
will  not  be  read  into  a  string.  Thus,  when  8tr_ws  is  in  effect,  a  string  is  terminated  by  an 
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end-of-line,  an  end-of-file,  a  begin  record  character  or  an  end  record  character  when 
no-8tr-V8  is  in  effect,  a  string  is  terminated  by  any  whitespace,  an  end-of-file,the  begin  record 
character,  or  the  end  record  character. 

For  example,  if  the  file  test .  in  contains  the  data 

First  line 

Second  line  {with  stuff  in  brackets  } 

then  the  code 

mainO 

OFFSRF-if  stream  ini  (  "test .  in" ) ; 

str  si,  s2,  83; 

ini  »  si  »  s2  »  s3: 

cout  «  si  «  endl  «  s2  <<  endl  «  83  <<  endl  «  endl; 
inl.closeO: 

OFFSRF-if  stream  in2("test .  in")  ; 
char  ch; 

in2  »  str-«s  »  si  >>  s2: 

in2  »  ch;  //  gobble  the  begin  record  character 
in2  »  s3; 

cout  «  si  <<  endl  «  s2  <<  endl  <<  sS  «  endl; 
in2. close 0 ; 

} 

will  have  the  following  output. 

First 

line 

Second 

First  line 
Second  line 

sith  stuff  in  brackets 

2.4  OFFSRF-ofBtxeam  manipulators 

An  OFFSRF-of  stream  provides  several  manipulators  which  ease  the  output  of  the  start  and 
end  of  an  OFFSRF  record.  The  manipulator  bgnrec(record.name)  begins  a  new  record  whose 
name  is  record-name.  A  bgnrec  manipulator  should  always  be  matched  by  the  manipulator 
endrec. 

Use  of  bgnrec  and  endrec  causes  nested  records  to  be  indented  automatically.  This  is 
implemented  by  overloading  the  manipulator  endl  so  that  it  indents  an  appropriate  number  of 
spaces. 

The  name  of  an  OFFSRF  record  can  be  followed  by  an  optional  colon  to  indicate  that  the 
remainder  of  the  line  contains  significant  data.  The  behaviour  of  bgnrec  and  endrec  depends 
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on  whether  the  colon  format  is  used.  Use  of  colon  formatting  is  enabled  with  an  optional  second 
argument  to  bgnrec:  if  this  argument  is  a  non-zero  integer,  colon  formatting  will  be  used.  The 
colon  formatting  is  automatically  disabled  by  the  endrec  and  endl  manipulators. 

When  colon  formatting  is  enabled,  bgnrec  writes  the  name  record-nane  preceded  by  a 
{  and  followed  by  a  colon.  It  then  increases  the  level  of  indenting  by  two  spaces,  endrec 
decrements  the  level  of  indenting  by  two  spaces,  writes  a  },  then  disables  the  colon  formatting. 

If  colon  formatting  is  disabled,  bgnrec  does  not  write  a  colon  after  the  record  name,  but 
it  does  start  a  new  line,  appropriately  indented,  endrec  starts  a  new  line  after  the  level  of 
indentation  has  been  reduced,  then  writes  the  }  followed  by  the  record  name. 

For  example 

OFFSRF-of stream  streamC'test  .out") ; 

stream  «  bgnrec ("TEST  RECORD")  «  123. 4S  «  endl 

«  bgnrec( "COMMENT" ,1)  <<  "This  is  a  comment."  <<  endrec 
«  endrec  <<  endl 

«  bgnrec ("RECORD  2",1)  <<  "  abcDEF"  <<  endrec  <<  endl 

«  bgnrec ("RECORD  3",1)  <<  "  abcDEF"  <<  endl  <<  endrec  <<  endl; 

causes  the  output  in  the  file  test .  out; 

{TEST  RECORD 
123.45 

{COMMENT: This  is  a  comment.} 

>TEST  RECORD 
{RECORD  2:  abcDEF} 

{RECORD  3:  abcDEF 

}REC0RD  3 

Notice  the  difference  between  RECORD  2  and  RECORD  3.  In  the  former,  endl  was  not  used  prior 

to  endrec,  so  that  the  colon  formatting  was  enabled  when  endrec  was  called.  In  the  latter,  the 

endl  manipulator  had  turned  off  the  colon  formatting  before  endrec  was  called. 

2.5  The  connected  file 

OFFSRF  streams  retain  the  name  of  the  file  to  which  they  are  connected.  The  name  of 
the  file  may  be  obtained  using  the  member  function  f  ile()  which  returns  a  str.  Thus, 

0FFSRF_if stream  streamC'test . in") ; 

cout  «  "The  connected  file  is  "  <<  stream. fileO  «  endl; 
will  cause  the  output 
The  connected  file  is  test. in 
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2.6  Verbose  and  terse  modes 


The  OFFSRF  streams  can  be  used  in  either  verbose  mode  or  terse  mode.  When  used 
in  verbose  mode,  extra  comments  will  be  written  to  cout  describing  the  state  of  the  input  or 
output.  When  in  terse  mode  these  optional  comments  will  be  suppressed. 

An  OFFSRF  stream  can  be  set  to  verbose  mode  using  the  manipulator  verbose;  it  can 
be  set  to  terse  mode  using  the  manipulator  terse.  The  current  mode  of  an  OFFSRF  stream 
may  be  obtained  using  the  int  function  is.verboseO  which  returns  zero  if  the  stream  is  not 
in  verbose  mode,  non-zero  otherwise.  By  default,  an  OFFSRF  stream  is  in  terse  mode. 

For  example,  in  verbose  mode,  an  OFFSRF.of  stream  echoes  the  start  and  end  of  all  records 
to  cout.  Thus 


OFFSRF-of  stream  stream  ("test  .out")  : 
stream  «  verbose 


«  bgnrecC'TEST  RECORD")  «  123.45  «  endl 

<<  bgnrecC" COMMENT",!)  «  "This  is  a  comment."  <<  endrec 
<<  endrec  <<  endl 


«  bgnrecC "RECORD  2")  «  "  abcDEF"  «  endrec  «  endl; 


will  cause  the  following  ortput  on  cout: 


<TEST  RECORD 
{COMMENT} 

} 


{RECORD  2} 


2.7  The  skiprecord  manipulator 

There  is  an  additional  manipulator  called  skiprecord  which  is  defined  for  OFFSRF  input 
streams.  It  skips  over  all  remaining  data  and  sub-records  in  the  current  record.  It  is  especially 
useful  for  skipping  records  which  you  know  will  appear  in  a  file  but  for  which  your  application 
has  no  use. 


2.8  is-recozdO,  is-dataC),  and  is_eor() 

When  reading  a  record  which  has  no  fixed  amount  of  data  (e.g.  a  list  of  names  of  unspecified 
length),  it  is  often  necessary  to  know  whether  the  next  entry  in  the  file  is  more  data,  the  start 
of  a  sub-record,  or  the  end  of  the  current  record,  ihe  functions  is-xecord(),  is.dataO,  and 
is.eorO  return  this  information.  Their  full  prototypes  are; 

int  is^ecord(OFFSRF-if  stream^) ; 
int  is_data(OFFSRF_if stream*) ; 
int  is.eorCOFFSRF-ifstreamft) ; 
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The  function  i8_record()  returns  non-zero  if  the  next  entry  in  the  rile  (not  including  whitespace 
or  comments)  is  the  start  of  a  new  sub-record.  The  function  is.eorO  returns  non-zero  if  the 
next  entry  in  the  file  is  the  end  of  the  current  record.  The  function  is.dataO  returns  non-zero 
if  the  next  entry  in  the  file  is  neither  the  start  of  a  sub-record  nor  the  end  of  the  current  record. 

3  The  OFFSRF  class 

The  header  file  OFFSRF. h  defines  a  virtual  class,  OFFSRF,  which  may  be  used  to  facilitate 
the  saving  and  restoring  of  C-f-l-  classes  in  OFFSRF  file  records. 

The  OFFSRF  class  defines  three  virtual  functions  with  the  following  prototypes: 

virtual  void  read-data(OFFSRF .if  stream  ftstream) ; 

virtual  int  readj:ecord(OFFSRF-ifstream  ^stream,  str  ftname,  int  skip  =  1); 

virtual  void  write(OFFSRF-of  stream  ftstream) ; 

The  function  read-data()  is  called  to  read  any  data  at  the  start  of  the  record  which  is  not 
contained  in  sub- records.  The  base  class  function  OFFSRF :  tread-dataO  does  nothing;  therefore, 
if  you  are  defining  a  class  which  reads  a  record  with  no  data,  you  need  not  explicitly  include  the 
function  read_data(). 

The  function  read-recordO  reads  a  sub-record  whose  name  is  name;  it  returns  non-zero 
if  the  record  was  read  correctly.  The  base  class  function  OFFSRF:  :read_record()  can  read 
COMMENT  records  (see  Reference  1,  Section  3.1),  and  INCLUDE  records  (see  Section  3.1).  The 
optional  argument  skip  is  a  flag  which  indicates  what  read-record ()  should  do  if  it  does  not 
recognize  the  record  name  in  name.  Usually  skip  is  simply  passed  to  OFFSRF:  :read_record() 
which  handles  it  as  follows.  If  skip  is  non-zero,  then  if  the  name  is  not  recognized  (i.e.  is  neither 
COMMENT  nor  INCLUDE),  then  the  skiprecord  manipulator  will  be  used  to  skip  the  record.  In 
this  case,  the  returned  value  of  OFFSRF: : read-record ()  will  be  non-zero.  If  skip  is  zero,  then 
if  the  name  is  not  recognized,  then  OFFSRF: : read-record ()  simply  returns  zero.  The  main 
use  for  the  skip  argument  is  for  the  implementation  of  classes  with  multiple  base  classes.  An 
example  is  given  in  Section  3.3. 

The  function  write ()  writes  all  the  data  for  the  current  record  into  stream.  The  base 
class  function  OFFSRF: : write ()  does  nothing. 

The  inserter  and  extractor  operators  for  OFFSRF  streams  are  overloaded  for  any  class  of 
base  type  OFFSRF.  Thus,  once  the  functions  read_data(),  read-recordO,  and  write ()  have 
been  defined,  an  object  obj  of  base  class  OFFSRF  can  be  read  from  an  OFFSRF _if  stream  in  by 

in  »  obj ; 

Similarly,  it  can  be  written  to  an  OFFSRF _of  stream  out  by 
out  «  obj ; 

There  is  a  single  constructor  for  the  OFFSRF  class;  the  constructor  has  no  arguments.  Be¬ 
cause  the  OFFSRF  class  consists  solely  of  virtual  functions  (with  the  exception  of  the  constructor), 
the  destructor  is  declared  to  be  virtual  as  well;  this  allows  the  deletion  of  an  object  via  a  pointer 
to  its  OFFSRF  base  class. 


3.1  INCLUDE  records 


The  base  class  function  OFFSRF:  :read_record()  understands  INCLUDE  records.  These 
records  have  the  form 

{INCLUDE;  file-name} 

A  new  OFFSRF _if  stream  is  associated  with  the  file  file-name  and  input  is  read  from  that  file 
until  it  is  finished.  The  included  file,  file-name,  may  include  only  records,  not  data;  however, 
%  data  may  be  included  in  any  sub-records  in  file-name. 

The  new  file  is  read  recursively  by  calling  the  virtual  function  read-record ()  associated 
with  the  current  this  pointer.  Section  3.4  points  out  some  difficulties  that  the  recursive  reading 
of  included  files  can  cause  if  one  is  not  wary. 

3.2  An  example 

The  use  of  the  OFFSRF  class  should  become  clearer  with  an  example.  Suppose  we  wish  to 
define  ship  offset  data  as  described  in  Reference  1,  Section  3.  For  this  example  only  the  data 
describing  the  transom  will  be  considered. 

The  transom  is  represented  as  a  plane  which  intersects  the  hull  near  the  stern.  The  transom 
plane  is  defined  by  specifying  a  point  through  which  it  passes,  and  a  normal  vector.  These  are 
specified  by  giving  values  of  four  quantities;  X,  Z,nx,  and  nz- 

The  data  describing  the  hull  will  be  read  from  a  file  called  ship .  in.  The  transom  is  defined 
by  a  TRANSOM  record  in  this  file.  The  TRANSOM  record  has  a  sub-record,  TRANSOM  OFFSETS  which 
gives  a  list  of  points  lying  on  the  edge  of  the  transom.  The  format  of  the  TRANSOM  record  is 

{TRANSOM;  X  Z  nx  nz 
{TRANSOM  OFFSETS 

X-value-1  Y-value-1  Z-value-1 
X-value-2  Y-value-2  Z-value-2 

X-value-n  Y-value-n  Z-value-n 
}TRANS0M  OFFSETS 
KRANSOM 

One  may  define  the  ship  class  to  describe  complete  offset  descriptions  of  a  ship,  the  transom 
class  to  describe  transoms,  and  the  transom_offset  class  to  describe  a  collection  of  transom 
offsets.  Each  of  these  classes  is  given  a  base  class  OFFSRF  so  that  they  may  be  initialized  by 
^  reading  an  OFFSRF  file. 

3.2.1  The  tiansom-ofFsets  class 

The  transom-off  sets  class  implements  the  offsets  as  simple  arrays  along  with  an  integer 
which  gives  the  number  of  points. 
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Since  no  explicit  sub-records  are  defined  for  the  TRANSOM  OFFSETS  record,  there  is  no  need 
to  provide  a  separate  implementation  of  read_record():  the  default  version  provided  by  the 
OFFSRF  base  class  will  do.  The  default  version  will  read  any  COMMENT  records  that  may  be 
included  in  the  record. 

The  function  transom-offsets :  :read-data()  reads  the  values  of  the  points  from  the  input 
stream.  The  function  is_data()  is  used  to  determine  whether  the  next  entry  in  the  file  is  more 
data.  Notice  that  is_eor()  should  not  be  used  here,  since  there  may  be  a  COMMENT  sub-record 
after  the  offset  data.  For  simplicity,  no  check  is  made  to  ensure  that  the  number  of  offsets  in 
the  file  does  not  exceed  MAX-N0_0FFSETS. 

The  function  transom-offsets:  :vr its ()  simply  writes  the  offset  data  to  the  output 
stream. 

iin'  ■  le  "OFFSRF. h" 

♦define  MAX.NO.OFFSETS  50 

class  transom.offsets:  public  OFFSRF 
{  int  num; 

double  XCMAX_N0_0FFSETS] ,  Y[MAX.N0_0FFSETS] .  Z[MAX_N0_0FFSETS] ; 
public: 

transom.offsets ()  {  num  =  0;  } 

virtual  void  read.data(OFFSRF_if stream  ftstream) 

{  num  *  0; 

vhile  (is .data (stream))  stream  »  XCixum]  >>  YCnum]  >>  ZCnum++] ; 

} 

virtual  void  write (OFFSRF.of stream  ftstream) 

{  for  (int  i  =  0;  i  <  num;  i++) 

stream  <<  X[i]  <<  "  "  <<  Y[i]  «  "  "  <<  Z[i]  <<  endl; 

} 

}; 


3.2.2  The  transom  class 

The  transom  class  contains  the  four  parameters  X,  Z,  nx,  and  nz,  and  a  pointer  to  an 
object  of  class  transom_offsets.  The  function  transom:  ;read-data()  reads  the  values  of  X, 
Z,  nxi  and  nz  using  the  extractor.  The  pointer  value  is  set  by  the  transom  class  constructor. 

The  function  transom:  :readj'ecord()  reads  a  TRANSOM  OFFSETS  record  using  the  extrac¬ 
tor  to  read  the  transom-off sets  object  pointed  at  by  to.  Notice  that  there  is  no  need  to  call 
transom-of f sets :  :read-data()  explicitly;  the  extractor  handles  everything. 

If  the  record  name  is  not  understood  by  transom:  :read_record(),  it  is  passed  to  the 
default  read-recordO  defined  in  the  base  class.  This  ensures  that  COMMENT  and  INCLUDE 
records  will  get  read  properly. 
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The  function  transom;  :  write ()  uses  the  manipulators  bgnrec  and  endrec  and  the  inserter 
«  to  write  the  TRANSOM  OFFSETS  record.  Again,  the  function  tremsom_off  sets : :  write  ()  need 
not  be  called  explicitly. 

class  transom:  public  OFFSRF 
<  double  X,  Z,  n.X,  n_Z; 
transom. off sets  *to; 

*  protected: 

virtual  void  read.dataCOFFSRF.ifstream  tstream) 

{  stream  »  X  »  Z  »  n.X  »  n.Z;  } 

virtual  int  read.recordCOFFSRF. if stream  Astream,  str  ftname,  int  skip=l) 

{  int  error  *  1; 

if  (name  ==  "TRANSOM  OFFSETS")  stream  »  *to; 
else  error  -  OFFSRF: ;read.record(stream, name, skip) ; 
return  error; 

> 

virtual  void  write(OFFSRF.ofstream  ftstream) 

•C  stream  «  X  «  "  "  «  Z  «  "  "  «  n.X  «  "  "  «  n.Z  «  endl 
«  bgnrec ("TRANSOM  OFFSETS")  <<  *to  <<  endrec; 

} 

public: 

transom(transom.offsets  *t) :  to(t)  ■(  } 

>; 


3.2.3  The  ship  class 

The  ship  class  is  defined  to  read  and  write  the  TRANSOM  record  using  the  extractor  and 
inserter  operators.  Its  only  data  member  is  a  pointer  to  a  transom;  the  pointer  is  set  when  the 
ship  is  constructed. 

class  ship: 

public  OFFSRF  {  transom  *tr; 
protected: 

virtual  int  read.record(OFFSRF. if stream  Astream,  str  Aname,  int  skip=l) 

<  error  =  1; 

if  (name  ==  "TRANSOM")  stream  »  etr; 

else  error  ^  OFFSRF: :read.record (stream, name, skip) ; 

return  error; 

} 
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virtual  void  write (OFFSRF.of stream  tstream) 

•C  stream  <<  bgnrecC "TRANSOM")  «  *tr  «  endrec  <<  endl; 

> 

public : 

shipCtransom  *t):  tr(t)  {  } 

}; 


3.2.4  The  function  main() 

The  following  example  program  simply  creates  objects  of  class  transom_of  f  sets,  tremsom, 
and  ship,  then  reads  data  to  define  them  from  the  file  ship .  in.  The  data  is  then  written  into 
the  file  ship .  out. 

mainO 

{  transom. off sets  to; 
transom  tr(ftto) ; 
ship  s(ttr) ; 

OFFSRF. if stream  inC'ship.in") ; 
in  »  s; 

OFFSRF.ofstream  outC'ship.out") ; 
out  «  s; 

> 


Following  is  a  sample  input  file  ship .  in.  The  TRANSOM  OFFSETS  record  is  read  from  the 
included  file  troffsets.in. 

!This  is  a  test  file  containing  ship  data 
{COMMENT: Reading  sample  ship  data.} 

{UNKNOWN  RECORD 

{COMMENT: This  record  should  be  skipped.} 

} 

{TRANSOM:  1.0  2.0  3.0  4.0 

{COMMENT: Reading  TRANSOM  record} 

{INCLUDE:  troffsets.in  } 

} 


And  here  is  the  file  trof f  sets .  in. 

IThis  file  contains  a  TRANSOM  OFFSETS  record.  It  can  be  included 
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!into  a  TRAKSOM  record. 

•CTRAMSOM  OFFSETS 
12  3 
4  5  6 
7  8  9 

{COMMENT: Reading  TRANSOM  OFFSETS  record} 

} 


» 


3.3  Classes  with  Multiple  OFFSRF  Base  Classes 

It  is  sometimes  desirable  for  a  class  to  be  derived  from  more  than  one  base  class,  each  of 
which  is  derived  from  the  OFFSRF  class.  For  example,  suppose  that  class  X  is  derived  from  the 
OFFSRF  class  and  knows  how  to  read  in  the  record  X-RECORD.  Similarly,  class  Y  is  derived  from 
the  OFFSRF  class  and  knows  how  to  read  in  the  record  Y-RECORD. 

class  X:  virtual  public  OFFSRF 

{  int  x; 

protected: 

virtual  int  read_record(OFFSRF_if stream  Astream,  atr  ftname,  int  skip=l) 

{  int  error  *  1; 

il  (name  *  "X-RECORD")  stream  »  x; 

else  error  *  OFFSRF: :read.record( stream, name, skip) ; 

return  error; 

} 

}; 


class  Y:  virtual  public  OFFSRF 
•C  int  y; 
protected : 

virtual  int  read_record(OFFSRF_ifstream  Astream,  atr  Aname,  int  skip^l) 
{  int  error  =  1; 

if  (name  *  "Y-RECORD")  stream  »  y; 

else  error  »  OFFSRF: :read.record(stream, name, skip) ; 

return  error; 

} 

>; 


Now  suppose  that  class  XY  is  derived  from  both  X  and  Y.  (Notice  that  OFFSRF  is  a  virtual  base 
class  for  both  X  and  Y  since  only  one  copy  of  the  OFFSRF  base  class  is  ever  necessary.) 

class  XY:  public  X,  public  Y 

protected: 
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virtual  int  read.record(OFFSRF_if stream  ftstream,  str  ftname,  int  skip=l); 


}; 


We  wish  the  read-record()  function  of  XY  to  be  able  to  read  both  X-RECORD  and  Y-RECORD 
records.  This  can  be  handled  conveniently  using  the  skip  argument  of  read_record()  as  follows. 

int  XY: :read_record(OFFSRF_if stream  tstream,  str  tname,  int  skip) 

■C  if  (X: :read_record(streaffl,name,0))  return  1; 
return  Y: :read_record(stream, name. skip) ; 

} 

This  function  sends  the  record  name  to  each  of  its  base  classes  in  turn.  By  setting  the  skip 
argument  to  zero  when  X:  :readj:ecord()  is  called,  we  ensure  that  if  it  does  not  understand 
the  name,  then  it  will  simply  return  zero  without  reading  any  further  in  stream.  Thus,  if 
X: : read-record ()  returns  zero,  then  Y: : read-record ()  can  be  called  to  read  the  record. 

3.4  OFFSRF  Classes  with  OFFSRF  Class  Members 

Suppose  that  class  X  and  class  Y  are  both  derived  from  the  OFFSRF  class,  but  that  X  is  a 
member  of  Y.  As  in  the  previous  section,  we  will  assume  that  X  knows  how  to  read  an  X-RECORD 
and  that  Y  knows  how  to  read  a  Y-RECORD. 

class  X:  virtual  public  OFFSRF 

{  int  x; 

public: 

virtual  int  read_record(OFFSRF_if stream  ftstream,  atr  ftname,  int  skip*l); 

}; 


class  Y:  virtual  public  OFFSRF 
•C  int  y; 

X  ztemp; 
protected : 

virtual  int  read_record(OFFSRF.if stream  ftstream,  atr  ftname,  int  skip=l); 

}; 


Commonly,  the  OFFSRF  data  file  is  set  up  to  reflect  the  class  hierarchy,  so  that  the 
X-RECORD  will  be  a  sub-record  of  the  Y-RECORD: 

{Y-RECORD:  123.4 
{X-RECORD:  567.8  } 

}Y-REC0RD 

In  this  case,  the  function  Y: :  read-record  ()  is  straightforward. 
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int  Y: :read_record(OFFSRF_if stream  tstream,  atr  tname,  int  8kip=l) ; 

{  int  error  »  1; 

if  (name  *  "X-RECORD")  stream  »  xtemp; 

else  error  «  OFFSRF: :read_record(stream, name, skip) ; 

return  error; 

} 

void  Y: :read_data(OFFSRF_if stream  tstream) 

{  stream  »  y; 

»  } 

However,  suppose  that  it  is  desired  that  X-RECORD  and  Y-RECORD  have  an  equal  footing  in  the 
*  OFFSRF  data  file; 

<X-REC0RD:  567.8  } 

{Y-RECORD;  123.4  } 

When  the  X-RECORD  is  read  we  want  its  value  to  initialize  Y: : xtemp. x.  This  can  be  achieved 
using  the  skip  argument  to  Y:  :read-record(). 

int  Y: :read_record(OFFSRF_if stream  ftstream,  atr  kname,  int  skipsl); 

{  error  ■  1; 

if  (str  **  "Y-RECORD")  stream  »  y; 

else  error  s  xtemp. read.recordCstream, name, skip) ; 

return  error; 

} 

Notice  that  the  class  Y  must  have  access  to  the  X  member  function  X:  :read-record();  hence, 
either  X: : read-record ()  should  be  declared  public  (as  above),  or  Y  should  be  declared  a  friend 
of  the  class  X. 

The  above  example  of  Y: : read-record ()  has  a  not- very-obvious  problem.  Suppose  that  in¬ 
stead  of  an  X-RECORD  or  Y-RECORD,  there  is  an  INCLUDE  record  which  directs  input  to  a  file  where 
the  X-RECORD  and  Y-RECORD  are  found.  The  record  Y-RECORD  will  not  be  read  from  the  included 
file.  Why  not?  When  Y: : read-record ()  encounters  the  INCLUDE  record,  control  is  passed  via 
X: : read-record ()  to  OFFSRF:  :read-r0cord(),  which  o^jens  a  new  input  stream  and  starts  to 
reawi  the  records  within  it  recursively.  To  read  the  records,  the  function  X: :  read-record ()  is 
used,  since  the  current  this  pointer  points  to  an  object  of  class  X.  Since  X :  read-record ()  does 
not  know  how  to  read  a  Y-RECORD  record,  it  will  be  skipped. 

The  solution  to  the  problem  is  to  call  OFFSRF: : read-record ()  before  X;  :read_record() 
to  pick  up  any  INCLUDE  records. 

int  Y: :read_record(OFFSRF_if stream  kstream,  atr  kname,  int  skip=l) ; 

{  error  *  1; 

if  (str  *»  "Y-RECORD")  stream  »  y; 

„  else  if  (OFFSRF: :read_record(8tream, name, 0))  return  1; 

else  error  »  xtemp. read_record(stream, name, skip) ; 
return  error; 

} 
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4  Concluding  Remarks 


A  set  of  classes  to  ease  the  use  of  OFFSRF  data  files  has  been  described.  The  parsing  of 
the  OFFSRF  record  structure  is  handled  by  defining  a  input  stream  class  OFFSRF_ifstream. 
The  associated  output  stream  class  OFFSRF.of  stream,  along  with  its  manipulators  bgnrec  and 
endrec,  provide  a  simple  means  of  writing  output  files  which  are  properly  indented  and  which 
have  matching  begin  and  end  record  markers. 

Several  manipulators  have  been  defined  for  these  streams  in  order  to  provide  the  pro¬ 
grammer  with  some  flexibility  in  their  use.  Of  course,  all  the  standard  istream  and  ostream 
manipulators  will  also  work. 

Classes  can  easily  be  made  to  read  OFFSRF  records  by  deriving  them  from  the  OFFSRF  base 
class  and  defining  the  three  virtual  functions  read_record(),  read-data(),  and  writeO.  No 
parsing  of  the  OFFSRF  record  names  is  necessary.  Moreover,  the  insertion  (>>  and  extraction 
(»)  operators  have  been  overloaded  for  all  classes  derived  from  the  OFFSRF  base  class,  so  that 
reading  the  file  can  be  done  in  a  very  concise  and  elegant  way. 


Appendix 

A  The  str  class 


The  class  str  is  a  representation  of  character  strings.  It  is  safer  to  use  than  ordinary  arrays 
of  cheur  since  memory  usage  is  strictly  controlled.  In  addition,  there  are  many  member  functions 
which  make  the  str  class  easy  to  use.  In  the  OFFSRF  class  uses  the  str  class  to  represent  record 
names. 

Automatic  type  conversion  from  str  to  char*  is  provided  so  that  a  str  can  be  used  as  an 
argument  to  any  function  which  requires  a  char*;  however,  type  conversion  from  chau:*  to  str 
must  be  done  explicitly  using  either  the  string  constructors  or  the  function  ch28tr()  which, 
given  a  const  char*  argument,  returns  the  equivalent  str. 

The  definition  of  the  str  class  is  contained  in  the  header  file  str.h. 

A.l  Constructors 

An  instance  of  a  str  may  be  declared  in  five  ways. 

str  s:  declares  s  to  be  a  string  of  length  zero.  No  memory  is  allocated  for  the  characters  in 
the  string. 

str  s(n):  where  n  is  an  integer,  declares  s  to  be  a  string  of  length  n.  Enough  memory  will  be 
allocated  for  n+1  characters;  the  extra  memory  location  is  so  that  a  trailing  null  character 
can  be  appended  if  the  str  is  converted  to  char*. 

str  sCn.m):  where  n  and  m  are  integers,  declares  s  to  be  a  string  of  length  n.  Enough  memory 
is  allocated  for  either  m  or  n  characters,  whichever  is  greater. 

str  s(t):  where  t  is  another  str  initializes  s  by  copying  t. 

str  s(t):  where  t  is  of  type  cheu:*  initializes  s  by  copying  t  up  to  the  first  null  character. 
Enough  memory  is  allocated  to  contain  the  all  characters  including  the  null. 

A. 2  Member  Functions 

The  following  member  functions  are  defined  for  the  str  class, 
int  len():  returns  the  length  of  the  string. 

int  maxJLenO:  returns  the  maximum  length  of  the  string  available  with  the  current  memory 
allocation. 

void  set-len(int  n):  changes  the  length  of  the  string  to  n.  If  there  is  not  enough  memory 
currently  allocated,  more  will  be  allocated  and  the  current  contents  of  the  string  will  be 
copied  to  the  new  memory. 
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void  set  jsemdnt  m) :  changes  the  memory  allocation  so  that  a  string  of  length  m  can  be  stored. 

If  B  is  less  than  the  current  allocation,  nothing  is  done. 

void  strip-leading-HsC):  strips  whitespace  from  the  beginning  of  a  string  (whitespace  is  de¬ 
fined  as  any  characters  for  which  the  C  function  isspaceO  returns  true). 

void  8trip-trailing-vs():  strips  whitespace  from  the  end  of  a  string. 

void  strip_vs():  strips  whitespace  from  the  beginning  and  the  end  of  a  string. 

« 

void  shiftr(int  n,  int  lo,  int  hi):  shifts  the  characters  between  lo  and  hi,  n  places  to 
the  right.  If  a  character  is  shifted  past  the  end  of  the  string,  it  is  lost.  If  n  is  negative, 
the  shift  is  to  the  left.  ♦ 

void  shiftlCint  n,  int  lo,  int  hi);  is  like  shiftrO  but  shifts  the  characters  to  the  left 
for  positive  n  and  to  the  right  for  negative  n. 

void  shiftcCint  n):  does  a  circular  shift  of  the  whole  string  by  n  places  to  the  right:  i.e.  the 
array  is  shifted  to  the  right  but  characters  which  are  shifted  past  the  end  of  the  array  are 
copied  to  the  beginning.  If  n  is  negative,  the  shift  is  to  the  left. 

void  insert  (const  char  At,  int  i):  inserts  the  character  t  at  the  i‘^  position  in  the  string. 

The  length  of  the  string  is  increased  by  one. 

void  insert  (const  str  As,  int  i):  inserts  the  string  s  into  the  current  string  starting  at 
the  the  i‘**  character.  The  length  of  the  string  is  increased  by  the  length  of  a. 

if  stream  Aread(if  stream  Astream):  reads  a  str  from  a  binary  input  stream.  The  length,  n, 
is  read  first,  then  the  next  n  bytes  in  the  file  are  read  and  interpreted  as  characters. 

of  stream  Avrite  (of  stream  Astream);  writes  a  str  to  a  binary  output  stream. 

A.3  Overloaded  Operators 

The  following  operators  are  overloaded  for  the  str  class.  Let  si  have  type  str  and  let  s2 
have  type  str  or  char*. 

sl[i]:  returns  element  i  of  si. 

si  »  s2:  copies  str  s2  to  si  and  returns  si. 

sl(i,  j):  returns  a  copy  of  the  sub-string  from  element  i  to  element  j. 

si  +=  82:  appends  s2  to  si  and  returns  the  value. 

si  ♦  s2:  returns  a  str  created  by  concatenating  si  and  s2. 

si  =*  s2:  returns  true  (non-zero)  if  the  length  of  si  and  s2  are  the  same  and  the  characters  in 
each  are  the  same. 

si  !=  82:  returns  !  (si  =*  s2). 
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A. 4  Inserter  and  Extractor 

The  inserter  <<  writes  a  str  to  an  ostreaua.  The  extractor  >>  reads  characters  from  an 
istrean  until  whitespace  is  found.  These  functions  are  equivalent  to  reading/ writing  a  char* 
before/after  conversion  to  str. 
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